HAL SD types migration ¶

This section provides information about HAL SD types and structures for STM32 HAL1 to HAL2 migration.

HAL SD callback ID type definition ¶

HAL1	HAL2
typedef enum { HAL_SD_RX_CPLT_CB_ID, HAL_SD_TX_CPLT_CB_ID, HAL_SD_ERROR_CB_ID, HAL_SD_ABORT_CB_ID, HAL_SD_READ_DMA_LNKLST_BUF_CPLT_CB_ID, HAL_SD_WRITE_DMA_LNKLST_BUF_CPLT_CB_ID, HAL_SD_READ_DMA_DBL_BUF0_CPLT_CB_ID, HAL_SD_READ_DMA_DBL_BUF1_CPLT_CB_ID, HAL_SD_WRITE_DMA_DBL_BUF0_CPLT_CB_ID, HAL_SD_WRITE_DMA_DBL_BUF1_CPLT_CB_ID, HAL_SD_MSP_DEINIT_CB_ID, HAL_SD_MSP_INIT_CB_ID } HAL_SD_CallbackIDTypeDef;	Removed from HAL2 : the callback registration is managed by dedicated functions for each pssi event. For more details, refer to HAL SD callback registration. `HAL_SD_MSP_DEINIT_CB_ID` and `HAL_SD_MSP_INIT_CB_ID` are removed because the functions `HAL_SD_MspInit()` and `HAL_SD_MspDeInit()` are removed.

HAL1

HAL2

                typedef enum
{
  HAL_SD_RX_CPLT_CB_ID,
  HAL_SD_TX_CPLT_CB_ID,
  HAL_SD_ERROR_CB_ID,
  HAL_SD_ABORT_CB_ID,
  HAL_SD_READ_DMA_LNKLST_BUF_CPLT_CB_ID,
  HAL_SD_WRITE_DMA_LNKLST_BUF_CPLT_CB_ID,
  HAL_SD_READ_DMA_DBL_BUF0_CPLT_CB_ID,
  HAL_SD_READ_DMA_DBL_BUF1_CPLT_CB_ID,
  HAL_SD_WRITE_DMA_DBL_BUF0_CPLT_CB_ID,
  HAL_SD_WRITE_DMA_DBL_BUF1_CPLT_CB_ID,
  HAL_SD_MSP_DEINIT_CB_ID,
  HAL_SD_MSP_INIT_CB_ID
} HAL_SD_CallbackIDTypeDef;

               

Removed from HAL2 : the callback registration is managed by dedicated functions for each pssi event. For more details, refer to HAL SD callback registration.

HAL_SD_MSP_DEINIT_CB_ID and HAL_SD_MSP_INIT_CB_ID are removed because the functions HAL_SD_MspInit() and HAL_SD_MspDeInit() are removed.

Related concepts:

HAL SD state type definition ¶

HAL1	HAL2
typedef enum { HAL_SD_STATE_RESET, HAL_SD_STATE_TIMEOUT, HAL_SD_STATE_READY, HAL_SD_STATE_PROGRAMMING, HAL_SD_STATE_RECEIVING, HAL_SD_STATE_TRANSFER, HAL_SD_STATE_BUSY, HAL_SD_STATE_ERROR } HAL_SD_StateTypeDef;	typedef enum { HAL_SD_STATE_RESET, HAL_SD_STATE_INIT, HAL_SD_STATE_CARD_REMOVED, HAL_SD_STATE_IDLE, HAL_SD_STATE_ACTIVE, HAL_SD_STATE_ABORT } hal_sd_state_t;

HAL1

HAL2

                typedef enum
{
  HAL_SD_STATE_RESET,

  HAL_SD_STATE_TIMEOUT,

  HAL_SD_STATE_READY,

  HAL_SD_STATE_PROGRAMMING,

  HAL_SD_STATE_RECEIVING,
  HAL_SD_STATE_TRANSFER,
  HAL_SD_STATE_BUSY,

  HAL_SD_STATE_ERROR

} HAL_SD_StateTypeDef;

                typedef enum
{
  HAL_SD_STATE_RESET,

  HAL_SD_STATE_INIT,
  HAL_SD_STATE_CARD_REMOVED,

  HAL_SD_STATE_IDLE,

  HAL_SD_STATE_ACTIVE,

  HAL_SD_STATE_ABORT
} hal_sd_state_t;

Related concept: Revised and optimized HAL state machine

HAL SD DMA buffer memory type definition ¶

HAL1	HAL2
typedef enum { SD_DMA_BUFFER0, SD_DMA_BUFFER1 } HAL_SDEx_DMABuffer_MemoryTypeDef;	Multi-buffering is available only in some STM32 series. These series are not yet supported in HAL2.

HAL SD CID type definition ¶

HAL1	HAL2
typedef struct { __IO uint32_t ProdName1, __IO uint32_t ProdSN, __IO uint16_t OEM_AppliID, __IO uint16_t ManufactDate, __IO uint8_t ManufacturerID, __IO uint8_t ProdName2, __IO uint8_t ProdRev, __IO uint8_t Reserved1, __IO uint8_t CID_CRC, __IO uint8_t Reserved2 } HAL_SD_CardCIDTypeDef;	typedef struct { uint32_t product_name_part1, uint32_t product_serial_nbr, uint16_t oem_app_id, uint16_t manufacturer_date, uint8_t manufacturer_id, uint8_t product_name_part2, uint8_t product_rev, uint8_t reserved1, uint8_t cid_crc, uint8_t reserved2 } hal_sd_card_cid_t;

HAL1

HAL2

                typedef struct
{
  __IO uint32_t ProdName1,
  __IO uint32_t ProdSN,
  __IO uint16_t OEM_AppliID,
  __IO uint16_t ManufactDate,
  __IO uint8_t  ManufacturerID,
  __IO uint8_t  ProdName2,
  __IO uint8_t  ProdRev,
  __IO uint8_t  Reserved1,
  __IO uint8_t  CID_CRC,
  __IO uint8_t  Reserved2
} HAL_SD_CardCIDTypeDef;

               

                typedef struct
{
  uint32_t product_name_part1,
  uint32_t product_serial_nbr,
  uint16_t oem_app_id,
  uint16_t manufacturer_date,
  uint8_t  manufacturer_id,
  uint8_t  product_name_part2,
  uint8_t  product_rev,
  uint8_t  reserved1,
  uint8_t  cid_crc,
  uint8_t  reserved2
} hal_sd_card_cid_t;

               

HAL SD CSD type definition ¶

HAL1	HAL2
typedef HAL_SD_CardCSDTypeDef	Removed; in HAL2 the Card Specific Data is handled internally by the driver. Thus this structure and the related `HAL_MMC_GetCSD()` are removed.

HAL SD card information type definition ¶

HAL1	HAL2
typedef struct { uint32_t CardSpeed, uint32_t CardType, uint32_t Class, uint32_t CardVersion, uint32_t RelCardAdd, uint32_t BlockNbr, uint32_t BlockSize, uint32_t LogBlockNbr, uint32_t LogBlockSiz } HAL_SD_CardInfoTypeDef;	typedef struct { /* Removed; See the below note for details. / / Removed; See the below note for details. / / Removed; See the below note for details. / / Removed; See the below note for details. */ uint32_t relative_addr, uint32_t blk_nbr, uint32_t blk_size_byte, uint32_t logical_blk_nbr, uint32_t logical_blk_size_byte } hal_sd_card_info_t;

HAL1

HAL2

                typedef struct
{
  uint32_t CardSpeed,
  uint32_t CardType,
  uint32_t Class,
  uint32_t CardVersion,
  uint32_t RelCardAdd,
  uint32_t BlockNbr,
  uint32_t BlockSize,
  uint32_t LogBlockNbr,
  uint32_t LogBlockSiz
} HAL_SD_CardInfoTypeDef;

               

                typedef struct
{
  /* Removed; See the below note for details. */
  /* Removed; See the below note for details. */
  /* Removed; See the below note for details. */
  /* Removed; See the below note for details. */
  uint32_t relative_addr,
  uint32_t blk_nbr,
  uint32_t blk_size_byte,
  uint32_t logical_blk_nbr,
  uint32_t logical_blk_size_byte
} hal_sd_card_info_t;

               

Note

CardSpeed field:

In HAL1, the CardSpeed field was used internally to identify the card speed mode.
In HAL2 this has been removed from the exported structure and maintained only for internal usage within the HAL driver.

CardType field:

In HAL1, the CardType field was used internally to identify the card type (storage capacity).
In HAL2 this has been removed from the exported structure and maintained only for internal usage within the HAL driver.

Class field:

In HAL1, the Class field has been used to store the card’s CCC register (Card Command Class), used internally to identify the command sets supported by the card.
In HAL2 this has been removed; not needed as HAL driver only covers the mandatory commands supported by all SD cards.

CardVersion field:

In HAL1, the CardVersion field was used to store the card version (SD specification version).
In HAL2, the card version can be retrieved separately after initialization using the HAL_SD_GetCardVersion() function, which returns the card version as a hal_sd_specification_version_t enumeration value. This feature can be enabled by setting USE_HAL_SD_GET_SPEC_VERSION to 1 in stm32tnxx_hal_conf.h.

HAL SD card status type definition ¶

HAL1	HAL2
typedef struct { __IO uint32_t ProtectedAreaSize, __IO uint16_t CardType, __IO uint16_t EraseSize, __IO uint8_t DataBusWidth, __IO uint8_t SecuredMode, __IO uint8_t SpeedClass, __IO uint8_t PerformanceMove, __IO uint8_t AllocationUnitSize, __IO uint8_t EraseTimeout, __IO uint8_t EraseOffset, __IO uint8_t UhsSpeedGrade, __IO uint8_t UhsAllocationUnitSize, __IO uint8_t VideoSpeedClass } HAL_SD_CardStatusTypeDef;	typedef struct { uint32_t protected_area_size_byte, uint16_t card_type, uint16_t erase_size, uint8_t data_bus_width, uint8_t secured_mode, uint8_t speed_class, uint8_t performance_move, uint8_t allocation_unit_size, uint8_t erase_timeout, uint8_t erase_offset, uint8_t uhs_speed_grade, uint8_t uhs_allocation_unit_size, uint8_t video_speed_class } hal_sd_card_status_t;

HAL1

HAL2

                typedef struct
{
  __IO uint32_t ProtectedAreaSize,
  __IO uint16_t CardType,
  __IO uint16_t EraseSize,
  __IO uint8_t  DataBusWidth,
  __IO uint8_t  SecuredMode,
  __IO uint8_t  SpeedClass,
  __IO uint8_t  PerformanceMove,
  __IO uint8_t  AllocationUnitSize,
  __IO uint8_t  EraseTimeout,
  __IO uint8_t  EraseOffset,
  __IO uint8_t  UhsSpeedGrade,
  __IO uint8_t  UhsAllocationUnitSize,
  __IO uint8_t  VideoSpeedClass
} HAL_SD_CardStatusTypeDef;

               

                typedef struct
{
  uint32_t protected_area_size_byte,
  uint16_t card_type,
  uint16_t erase_size,
  uint8_t  data_bus_width,
  uint8_t  secured_mode,
  uint8_t  speed_class,
  uint8_t  performance_move,
  uint8_t  allocation_unit_size,
  uint8_t  erase_timeout,
  uint8_t  erase_offset,
  uint8_t  uhs_speed_grade,
  uint8_t  uhs_allocation_unit_size,
  uint8_t  video_speed_class
} hal_sd_card_status_t;

               

HAL SD DMA link node configuration type definition ¶

HAL1	HAL2
#define SD_DMALinkNodeConfTypeDef SDMMC_DMALinkNodeConfTypeDef typedef struct { uint32_t BufferAddress uint32_t BufferSize } SDMMC_DMALinkNodeConfTypeDef;	Removed; In HAL2, linked-list node’s `BufferAddress` and `BufferSize` are passed in row to the configuration API ( HAL_SD_FillNodeConfig()).

HAL SD DMA link node type definition ¶

HAL1	HAL2
#define SD_DMALinkNodeTypeDef SDMMC_DMALinkNodeTypeDef typedef struct { __IO uint32_t IDMALAR, __IO uint32_t IDMABASER, __IO uint32_t IDMABSIZE } SDMMC_DMALinkNodeTypeDef;	typedef struct { uint32_t idma_node_offset, uint32_t idma_buffer_base_addr, uint32_t idma_buffer_size } hal_sd_node_t;

HAL1

HAL2

                #define SD_DMALinkNodeTypeDef  SDMMC_DMALinkNodeTypeDef
typedef struct
{
  __IO uint32_t IDMALAR,
  __IO uint32_t IDMABASER,
  __IO uint32_t IDMABSIZE
} SDMMC_DMALinkNodeTypeDef;

               

                typedef struct
{
  uint32_t idma_node_offset,
  uint32_t idma_buffer_base_addr,
  uint32_t idma_buffer_size
} hal_sd_node_t;

               

HAL SD DMA linked list type definition ¶

	HAL1	HAL2
Definition	SD_DMALinkedListTypeDef	Removed; HAL2 introduces a unified queue structure for linked list management. Refer to HAL SD linked-list DMA operations. To define a linked list in HAL2, use the `hal_q_t` type along with the `HAL_Q_Init()` and using the HAL SD addressing descriptor operation `HAL_SD_DescOps` as parameter as follows.
Example usage	SD_DMALinkedListTypeDef my_linked_list;	hal_q_t my_linked_list; HAL_Q_Init(&my_linked_list, HAL_SD_DescOps);

HAL SD handle type definition ¶

HAL1	HAL2
SD_HandleTypeDef	hal_sd_handle_t

HAL SD initialization type definition ¶

In HAL2, clock settings are grouped in the hal_sd_clock_config_t structure inside hal_sd_config_t.

HAL1	HAL2
#define SD_InitTypeDef SDMMC_InitTypeDef typedef struct { uint32_t ClockEdge, uint32_t ClockPowerSave, uint32_t ClockDiv, uint32_t BusWide, uint32_t HardwareFlowControl, uint32_t TranceiverPresent } SDMMC_InitTypeDef;	typedef struct { typedef struct { hal_sd_clock_edge_t clk_edge, hal_sd_clock_power_save_t clk_power_save, #if defined (USE_HAL_SD_AUTO_DETECTION_FREQUENCY) && (USE_HAL_SD_AUTO_DETECTION_FREQUENCY == 0) uint32_t clk_hz, /* ClockDiv is replaced by clk_hz, see below note for details */ #endif } hal_sd_clock_config_t; hal_sd_bus_wide_t bus_wide, hal_sd_hardware_flow_control_t hw_flow_ctrl, hal_sd_transceiver_t transceiver, uint32_t data_timeout_cycle, uint32_t stop_xfer_timeout_ms, uint32_t erase_timeout_ms } hal_sd_config_t;

HAL1

HAL2

                #define SD_InitTypeDef  SDMMC_InitTypeDef
typedef struct
{

  uint32_t ClockEdge,
  uint32_t ClockPowerSave,

  uint32_t ClockDiv,

  uint32_t BusWide,
  uint32_t HardwareFlowControl,
  uint32_t TranceiverPresent

} SDMMC_InitTypeDef;

                typedef struct
{
  typedef struct
  {
    hal_sd_clock_edge_t          clk_edge,
    hal_sd_clock_power_save_t    clk_power_save,
  #if defined (USE_HAL_SD_AUTO_DETECTION_FREQUENCY) && (USE_HAL_SD_AUTO_DETECTION_FREQUENCY == 0)
    uint32_t                     clk_hz,
    /* ClockDiv is replaced by clk_hz, see below note for details */
  #endif
  } hal_sd_clock_config_t;

  hal_sd_bus_wide_t              bus_wide,
  hal_sd_hardware_flow_control_t hw_flow_ctrl,
  hal_sd_transceiver_t           transceiver,

  uint32_t                       data_timeout_cycle,
  uint32_t                       stop_xfer_timeout_ms,
  uint32_t                       erase_timeout_ms
} hal_sd_config_t;

               

Note

In HAL1, the user had to provide the clock divider manually, by choosing from the defined division factors in SDMMC layer (SDMMC_NSPEED_CLK_DIV, SDMMC_HSPEED_CLK_DIV...).
In HAL2, the user provides the clock frequency, and the clock divider calculation is done internally based on the provided frequency. When USE_HAL_SD_AUTO_DETECTION_FREQUENCY is enabled, HAL2 automatically selects the SDMMC clock divider to reach the maximum supported bus frequency.

HAL SD instance type definition ¶

In HAL1, this define was a redirection to device.h in order to provide the SD instance.

In HAL2, the instances are provided with the following enumeration type.

HAL1	HAL2
#define SD_TypeDef	Removed; use the following enumeration type instead. typedef enum { HAL_SD_CARD_1, HAL_SD_CARD_2 } hal_sd_t;

HAL SD callback pointer type definition ¶

HAL2 splits callbacks: hal_sd_cb_t handles simple Error/Abort cases, while hal_sd_xfer_cb_t adds an event parameter to distinguish transfer completions (Tx or Rx).

HAL1	HAL2
typedef void (pSD_CallbackTypeDef)(SD_HandleTypeDef hsd)	typedef void (hal_sd_cb_t)(hal_sd_handle_t hsd) typedef void (hal_sd_xfer_cb_t)(hal_sd_handle_t hsd, hal_sd_event_cb_t cb_event);

HAL SD transceiver callback pointer type definition ¶

HAL1	HAL2
typedef void (*pSD_TransceiverCallbackTypeDef)(FlagStatus status)	typedef void (hal_sd_transceiver_cb_t)(hal_sd_handle_t hsd, hal_sd_transceiver_state_t state)